Skip to content

feat(orm): chainable skip() / offset() / take() on QueryBuilder - #277

Merged
1 commit merged into
v3from
feat/orm-skip-offset-take
Nov 5, 2026
Merged

1 commit merged into
v3from
feat/orm-skip-offset-take

Conversation

@andrevanzuydam

Copy link
Copy Markdown
Collaborator

Problem

An AI harness building on Tina4 reached for QueryBuilder.skip(n) and hit a wall: the query builder only exposed limit(count, offset?), with the offset trapped as a positional arg. Devs coming from Mongoose / Eloquent / Knex reach for .skip() / .offset() / .take() and fail — even though the DocStore Mongo cursor already has .skip() and to_mongo() already emits a skip key.

Change (minimal, additive)

Three thin chainable setters over the existing internals:

  • offset(n) — the SQL-native verb (offset was previously only reachable as limit(n, offset))
  • skip(n) — alias of offset; the Mongo/Eloquent name, matches the DocStore cursor + to_mongo()'s skip key
  • take(n) — alias of limit; the Eloquent name, pairs with skip (.skip(20).take(10))

Pagination flows to both the SQL get() path and to_mongo() with no further wiring. CLAUDE.md's QueryBuilder method list updated to match.

Tests (real SQLite, no mocks — positive + negative)

.skip(2).limit(2) returns the 3rd+4th rows; .offset() is identical; .take() sets the limit; skip-past-end returns empty (not an error); .skip(5).to_mongo() emits {"skip": 5}; methods return the builder. Mutation-proven: making skip() a no-op broke exactly the 3 skip-dependent tests.

Verification

pytest tests/test_query_builder.py → 59 passed on the v3 (3.13.157) base.

Parity

Python is the reference here; sibling PRs land the same API in tina4-php / tina4-ruby / tina4-nodejs.

🤖 Generated with Claude Code

An AI harness reached for QueryBuilder.skip() and hit a wall: only
limit(count, offset?) existed, with offset trapped as a positional arg.
Add offset() (SQL-native), skip() (alias of offset - the Mongo/Eloquent
name, matches the DocStore cursor + to_mongo()'s skip key) and take()
(alias of limit - the Eloquent name, pairs with skip). Flows to both the
SQL get() path and to_mongo() with no further wiring. Real-SQLite tests
(positive + negative + Mongo-path), mutation-proven.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Andre van Zuydam <andrevanzuydam@gmail.com>
@tina4stack tina4stack closed this pull request by merging all changes into v3 in 13fae16 Nov 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants